Skip to content

docs: document dynamic sandbox secrets - #25785

Open
dvdksn wants to merge 3 commits into
docker:mainfrom
dvdksn:codex/sbx-dynamic-secret-docs
Open

docs: document dynamic sandbox secrets#25785
dvdksn wants to merge 3 commits into
docker:mainfrom
dvdksn:codex/sbx-dynamic-secret-docs

Conversation

@dvdksn

@dvdksn dvdksn commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

Summary

Document the dynamic secret sources introduced for sbx secret set and sbx secret set-custom in docker/sandboxes#3946. Replace snapshot and host-environment credential workflows with native reference and command sources for GitHub, 1Password, and AWS Secrets Manager.

The generated CLI reference remains on v0.38.0 and will update as part of the complete v0.39.0 release vendor sync.

@netlify /ai/sandboxes/security/credentials/

Preview:

Generated by Codex

The sandbox credential guides only covered literal stored values and obsolete host-environment workflows. Document reference and command sources, refresh and verification controls, and provider-specific workflows for GitHub, 1Password, and AWS Secrets Manager.

Co-authored-by: Codex <noreply@openai.com>
@dvdksn dvdksn added this to the sbx/v0.39.0 milestone Aug 11, 2026
@dvdksn dvdksn added the status/review Pull requests that are ready for review label Aug 11, 2026

@docker-agent docker-agent left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assessment: 🟡 NEEDS ATTENTION

2 medium-severity style issues found in new content added to credentials.md. Both are introduced by this PR.

Comment thread content/manuals/ai/sandboxes/security/credentials.md Outdated
Comment thread content/manuals/ai/sandboxes/security/credentials.md Outdated
dvdksn and others added 2 commits August 11, 2026 14:26
The initial workflow gave OP_ACCOUNT and AWS_PROFILE more prominence than their optional role warranted. Move provider selector support into a note and keep the primary 1Password and AWS flows focused on registering references.

Co-authored-by: Codex <noreply@openai.com>
The refresh guidance conflated cache durations with on-demand resolution, and the provider-selection note described implementation rather than purpose. Separate the refresh modes, explain account and profile selection directly, and remove the semicolon flagged by review.

Co-authored-by: Codex <noreply@openai.com>
@dvdksn
dvdksn marked this pull request as ready for review August 11, 2026 14:59
@dvdksn
dvdksn requested a review from a team August 11, 2026 14:59

@docker-agent docker-agent left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assessment: 🟢 APPROVE

The documentation for dynamic sandbox secrets (--ref and --command sources for sbx secret set) is well-written and follows Docker style conventions. No high or medium severity issues were found.

All four changed files (credentials.md, workflows.md, get-started.md, copilot.md) are hand-authored documentation — no vendored or generated content. The new content uses correct voice ("you"), avoids hedge words, and is appropriately scoped to the feature being introduced.

@docker-agent docker-agent left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assessment: 🟡 NEEDS ATTENTION

One documentation clarity issue found in the added content.

--ref 'op://Work/Example/credential'
```

Dynamic custom secrets resolve on demand by default. Pass `--refresh` with a

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Custom secrets default to on-demand resolution, but service secrets default to 55-minute caching — no explanation given

Line 331 (added by this PR) states "Dynamic custom secrets resolve on demand by default." However, line 141 (existing) states "Resolved service secrets are cached for 55 minutes by default." These are different commands (sbx secret set-custom vs sbx secret set), so the difference may be intentional, but the PR does not explain why the two commands behave differently. A reader comparing the two sections will likely see a contradiction and be uncertain which behavior applies in their case.

If the difference is intentional (a design choice for sbx secret set-custom), add a brief note explaining why, for example: "Custom secrets are resolved on every use because each host may require a fresh value." If the defaults should match, align the text.

@docker-agent docker-agent left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assessment: 🟡 NEEDS ATTENTION

The PR clearly documents dynamic secret sources (--ref and --command) for both service secrets and custom secrets, and is well-structured overall. Two medium findings warrant attention:

  1. The NOTE about OP_ACCOUNT/AWS_PROFILE doesn't clearly state whether the account/profile is persisted at registration or must be set in the daemon environment at resolution time — the current wording could mislead users.
  2. Custom secrets default to on-demand resolution while service secrets default to 55-minute caching. The asymmetry is factually correct but not cross-referenced, which could surprise users switching between the two secret types.


> [!NOTE]
> To resolve a reference with a specific 1Password account or AWS profile, set
> `OP_ACCOUNT` or `AWS_PROFILE` when you run `sbx secret set`. `sbx` uses that

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] NOTE callout wording may confuse users about when OP_ACCOUNT/AWS_PROFILE must be set

The NOTE says to set OP_ACCOUNT or AWS_PROFILE "when you run sbx secret set", then adds that "sbx uses that account or profile whenever it resolves the secret." The second sentence implies the account/profile is persisted at registration — but it doesn't say that explicitly. Users could read the first sentence and conclude they only need the variable at registration time, and be confused if the daemon uses a different account at resolution time (e.g., if the variable isn't persisted and must be present in the daemon's environment too).

Consider clarifying the mechanism — for example: "The value is stored with the secret reference and used by the daemon at every resolution. You don't need to keep the variable set after registration."

--ref 'op://Work/Example/credential'
```

Dynamic custom secrets resolve on demand by default. Pass `--refresh` with a

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Custom secrets' on-demand default contrasts with service secrets' 55-minute cache default — asymmetry not called out

Service secrets cache for 55 minutes by default (documented a few sections above); custom secrets resolve on demand by default. Both defaults are correct in their own sections, but no cross-reference or explicit comparison is made. A user who reads only the custom secrets section won't know that the behavior differs from service secrets — they may be surprised by repeated slow lookups on every credential use, or assume the same 55-minute cache applies.

Consider adding a short note such as: "Unlike service secrets, which cache for 55 minutes by default, custom secrets resolve on demand on every use unless you pass --refresh <duration>."

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/ai status/review Pull requests that are ready for review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants